🐛 fix(contribute): make the task lease outlive the hub process (#5681) - #5688

Summary

A hub restart threw away every in-flight contributor task, then handed the identical issue back seconds later.

A contributor relay holds one task at a time and keeps working through a brief disconnect, re-asserting the task when it reconnects. The hub only honours that re-assertion if it can match a server-issued lease — deliberate, since #C4: a client must never be able to assert ownership of work the server did not assign. But leases lived only in the hub's memory. A restart emptied the registry, so after an upgrade no in-flight resume could match, the relay was told no active lease for this task, and the revoke interrupted a working agent mid-turn.

The waste was visible in the ordering: revoked at 14:24:40, the same issue re-assigned to the same relay at 14:24:44. Ownership was never in question — only the record of it. Self-upgrade rolls (#5391) make this routine rather than rare, and it hits every contributor holding a task at the moment of any restart.

The fix is option (1) from the issue: persist the lease. It is written to /data/contributors/task-leases.json on every assignment, renewal and release, and read back at startup, so a restart becomes just a longer-than-usual disconnect.

Why this does not weaken C4

The security posture was "never rebuild ownership from client-supplied fields". That never required the record to be volatile — only to be the server's:

• The restored record is one the hub itself wrote, and a resume is matched against it exactly as before, on {identity, task_id, repo, number, generation} and inside the window. The test asserts all six mismatch cases (wrong task / generation / repo / number / identity, and an unversioned gen == 0) are still refused after a restart.
• No credential is in the file. The scoped GitHub token is minted per assignment and delivered separately (contribute: gate contributor credentials on explicit task acceptance #2537). Restoring a lease grants the ability to re-adopt a task the hub already issued, never to obtain a credential without passing selectTask.
• Written 0600, unlike the sibling contributor ledgers' 0644 — this is an authorization record, not a report.
• A lease already past its expiry is dropped at load, not restored, so a stale file cannot resurrect a task that is no longer re-adoptable. A malformed file degrades to "no leases" — the pre-fix behavior.

Three couplings that had to move with it

Persisting the map alone would have been quietly wrong in three ways:

1. The renewed window is what gets persisted. Persisting only the assignment-time window would bring a task that had been progressing for longer than leaseTTL back already expired — precisely the defect A relay that reconnects inside the backoff window cannot resume its task — in-flight work is interrupted mid-turn #4260 fixed in memory.
2. taskGen is advanced past every restored generation at boot. It is an in-memory counter that restarts at zero, so persisting leases without this would let a post-restart assignment mint a fencing token that aliases a restored one, and the contributor: task ownership has no hub lease or safe operator revoke/requeue path #2568 Gate would accept a pre-restart straggler against a brand-new task. src/docs/design/agent-state-inventory.md residual 2 called this hazard out in advance — "any change that persists one without the other (e.g. 'let's make leases survive restarts') silently breaks the fence" — so that residual is now marked resolved, with the coupling stated in loadLeases and pinned by a test rather than carried only by that document.
3. A restored lease holds its work item for two minutes after boot. The double-assignment guard is built purely from live connections, which is empty right after a restart. Making the resume work without this would convert the old "lose the task" bug into two relays on one issue — which is the other half of the contract the issue asks to pin.

That third point is deliberately scoped, and the scoping is the part most worth reviewing. A lease is not a hold in steady state: a dropped socket keeps its lease so the relay can resume (#4260) while its item merely cools down (#2356's speculative hedge). Honouring leases as holds for the full 30-minute TTL would silently replace that hedge with a long park on every disconnect — a policy change nobody asked for. So the hold applies only to leases restored from the previous process, only for leaseHoldGraceAfterStart (2 min, against a 1-second relay reconnect backoff), and never to the requester's own lease. Leases minted by this process are never holds; their holders have live connections the existing guard already covers.

The lease also now carries the item's canonical worksource key, so the guard recognises external work — Linear/Jira items carry Number == 0 and put their identity in Key (#4245) — instead of colliding every such item as repo#0 (#5120).

Cluster claimed (files/functions)

• src/pkg/dashboard/contribute_ws.go — taskLease gains key/restored; recordLeaseForKey; save hooks in recordLease/renewLease/revokeLease/lookupLease's expiry drop; new persistedLease, saveLeasesLocked, loadLeases, pruneExpiredLeases, leasedIssueKeys; taskLeasesFile/startedAt on the hub; loadLeases at construction; prune in cleanupLoop; the lease exclusion in selectTask.
• src/pkg/dashboard/contribute_lease_restart_test.go (new, 11 tests), api_contribute_test.go (redirect the new file in redirectContributeWSDisk).
• src/docs/contributor-relay.md, src/docs/design/agent-state-inventory.md (rows 31/32 + residual 2), CHANGELOG.md.

Disjoint from the open hold-gated PRs — none of them touch pkg/dashboard/contribute_ws.go. Also disjoint from my own #5682 (pkg/escalation, pkg/scheduler, cmd/hive).

Validation

• go build ./..., go vet ./pkg/dashboard/, gofmt -l clean on every touched file. (gofmt flags eight other pkg/dashboard test files — pre-existing drift, not touched here.)
• go test ./pkg/dashboard/ passes in full, including TestSelectTask_DeclaredCapabilitiesDoNotAffectSelection, which is the test that catches an over-broad lease exclusion: a blanket hold fails it, the restart-scoped one does not.
• src/scripts/check-docs-links.py: 130 files, all links and anchors resolve.
• Mutation-checked, three ways — each mechanism is independently pinned, and none of the new tests passes vacuously:
  • Remove loadLeases() -> 5 tests fail, the end-to-end one on the incident's own string: the relay reconnecting after a hub restart was told "no active lease for this task".
  • Drop the persist-on-renew -> only TestLeaseRestart_RenewedWindowSurvives fails.
  • Drop the restored-lease hold -> only TestLeaseRestart_RestoredLeaseHoldsItsIssue fails.

Not claimed

Option (3) from the issue — drain in-flight tasks before exiting — is not here. The issue calls it complementary rather than a substitute, and it is: it shrinks the window but cannot close it, since an upgrade will not wait out a 20-minute turn. It is also a change to shutdown sequencing rather than to the lease, and belongs in its own PR. Option (2) (reconstruct from the task-run log) is not needed once (1) lands.

Related issues

Refs #5681. Related: #4260 (the resume contract this extends across a process boundary), #5390 (the clean close that precedes it), #5391, #5120, #4245, #2568, #2537, #2356.

Testing

• cd src && go build ./...
• cd src && go test ./... — ran ./pkg/dashboard/ in full (the only package touched); passes.

— hive: backend=claude model=claude-opus-5